Live Data, Paging, setModel and Implement your own renderer

Author
Peter Kuo, Engineer, Potix Corporation

Date
December 21, 2008

Version
ZK 3, ZK 5

Overview

In a real world web application, it's common to collect data from database, and show it in listbox or grid or tree. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of Live Data, Paging. To separate view from data, ZK also introduces the concept of model. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.

What's Live Data

The main idea of "live data" is to separate data from the view. Developers only have to manipulate the data model, and the data of view (UI Component) will be updated accordingly. Secondly, it shortens the response time of user since only the required data will be downloaded the first time.

What's Paging

Paging separates long content into multiple pages.

A paging component is used for this purpose. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.

<paging totalSize="100" pageSize="20"/>

Then, when a user clicks on the hyperlinks, the onPaging event is sent with an instance of org.zkoss.zul.event.PagingEvent to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.

<paging id="paging"/>
<zscript>
     List result = new SearchEngine().find("ZK");
     //assume SearchEngine.find() will return a list of items.
     paging.setTotalSize(result.size());
     paging.addEventListener("onPaging", new EventListener() {
             public void onEvent(Event event) {
             int pgno = event.getPaginal().getActivePage();
             int ofs = pgno * event.getPaginal().getPageSize();
             new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1);            //assume redraw(List result, int b, int e) will display
             //from the b-th item to the e-th item
         }
     });
</zscript>

What's Model

To assign data to a component (e.g. grid or listbox), you have to prepare the data in certain data model. For example, listbox and grid accept interfaces ListModel and GroupsModel, while tree only accepts TreeModel. See the setModel method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.

ZK has implemented following Models:

SimpleCategoryModel
SimpleGroupsModel
SimpleListModel
SimplePieModel
SimpleTreeModel
SimpleXYModel
SimpleXYZModel
SimpleHiLoModel

What's Renderer

A renderer is responsible for rendering the layout of certain model. For example, RowRenderer is responsible for rendering data stored in the ListModel to the specified row in the Grid.

ZK has provided default renders:

Three Steps to Use Live Data

Prepare the data in the form of ListModel. ZK has a concrete implementation called org.zkoss.zul.SimpleListModel for representing an array of objects.
Implement the org.zkoss.zul.RowRenderer interface for rendering a row of data into the Grid.
- This is optional. If it is not specified, the default rowrender is used to render the data into the first column.
- You could implement different renderers for represent the same data in different views.
Specify the data in the model property, and, optionally, the rowrender in the rowRenderer property.

Examples

Single-Column Example : Using only setModel

In the following example, an array of data("data") is prepared , it is passed as a parameter for the generation of a ListModel("strset"). Last, assign this ListModel into a Grid by setting the model of the Grid.

<window title="Live grid">
	<zscript>
	<![CDATA[  
		String[] data = new String[30];
		for(int j=0; j < data.length; ++j) {
			data[j] = "option "+j;
		}		  
		ListModel strset = new SimpleListModel(data);
	]]>
	</zscript>
	<grid model="${strset}">
		<columns>
			<column label="options" />
		</columns>
	</grid>
</window>

Two-Columns Example : User defined renderer

Since the default rowrender only satisfies the scenario of single-column, a customized rowrenderer must be implemented to commit the scenario of multi-column. In the following example, a two-columns live data for grid is demonstrated.

1.Prepare the Data Model

The first step is to prepare required data. A two-way array is adopted in this example and it is passed as a parameter for the generation of a ListModel which is implemented by SimpleListModel. In addition, ListModel now supports various data types,including Array, List, Map, and Set in the form of ListModelArray,ListModelList, ListModelMap,and ListModelSet.

//prepare the data model 
String[][] model = new String[100][2]; 
for(int j=0; j < model.length; ++j) { 
	model[j][0] = "key"+j;
	model[j][1] = "value"+j; 
} 
ListModel strset = new SimpleListModel(model);

2.Define the RowRenderer Class

Secondly, to define a class which implements the interface RowRenderer,its method render(Row row, java.lang.Object data) is required to be implemented.

   Method render(Row row, java.lang.Object data)
   row - The row to render the result.
   data - Returned from ListModel.getElementAt()

In addition to pass required parameters into the method render(), the form of view (UI Component) for displaying data in the Grid also has to be defined, and any component which is supported by Grid could be adopted. In this example, Label is adopted, and the last step is to render Label into the specified row in the Grid by calling Label.setParent(Row row).

MyRowRenderer.java

import org.zkoss.zul.Label;
import org.zkoss.zul.Row;
import org.zkoss.zul.RowRenderer;

//define the RowRenderer class 
public class MyRowRenderer implements RowRenderer{ 
 
	public void render(Row row, java.lang.Object data) {
		String[] _data = (String[])data;
		new Label(_data[0]).setParent(row); 
		new Label(_data[1]).setParent(row);
	}
}

3.Specify model and rowRenderer Property

The properties of model and rowRenderer could be specified directly in the Grid. In this example,methods, Grid.setModel() and Grid.setRowRenderer() are adopted to specify required objects for realizing the idea of "live data".

<window title="Two-Column Live Data Demo" >
	<grid id="mygrid">
		<columns>
			<column label="key" />
			<column label="value" />
		</columns>
	</grid>
	<zscript><![CDATA[
		String[][] model = new String[100][2]; 
		
		for(int j=0; j < model.length; ++j) { 
			model[j][0] = "key"+j;
			model[j][1] = "value"+j; 
		} 
		ListModel strset = new SimpleListModel(model); 
		mygrid.setModel(strset); 
		mygrid.setRowRenderer(new MyRowRenderer());	 
	]]>
	</zscript>
</window>

If extreme large data set, say 1,000,000?

Check implement paging for listboxes with many items under: [[1]]

Data Binding

Not only showing the data by model, you can also modify underlying model by UI in real time.

ZK_Essentials/Displaying_Information_in_a_Grid_Using_Data_Binding/The_Concept_of_Data_Binding

Anonymous